

    \filetitle{acf}{Autocovariance and autocorrelation function for model variables}{model/acf}

	\paragraph{Syntax}

\begin{verbatim}
[C,R,List] = acf(M,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\tightlist
\item
  \texttt{M} {[} model {]} - Solved model object for which the ACF will
  be computed.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{C} {[} namedmat \textbar{} numeric {]} - Auto/cross-covariance
  matrices.
\item
  \texttt{R} {[} namedmat \textbar{} numeric {]} -
  Auto/cross-correlation matrices.
\item
  \texttt{List} {[} cellstr {]} - List of variables in rows and columns
  of \texttt{C} and \texttt{R}.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}applyTo=\textquotesingle{}} {[} cellstr
  \textbar{} char \textbar{} \emph{\texttt{@all}} {]} - List of
  variables to which the
  \texttt{\textquotesingle{}filter=\textquotesingle{}} will be applied;
  \texttt{@all} means all variables.
\item
  \texttt{\textquotesingle{}contributions=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - If \texttt{true}
  the contributions of individual shocks to ACFs will be computed and
  stored in the 5th dimension of the \texttt{C} and \texttt{R} matrices.
\item
  \texttt{\textquotesingle{}filter=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - Linear filter that is applied to
  variables specified by `applyto'.
\item
  \texttt{\textquotesingle{}nFreq=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{256}} {]} - Number of equally spaced
  frequencies over which the filter in the option
  \texttt{\textquotesingle{}filter=\textquotesingle{}} is numerically
  integrated.
\item
  \texttt{\textquotesingle{}order=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{0}} {]} - Order up to which ACF will be
  computed.
\item
  \texttt{\textquotesingle{}matrixFmt=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}namedmat\textquotesingle{}}}
  \textbar{} \texttt{\textquotesingle{}plain\textquotesingle{}} {]} -
  Return matrices \texttt{C} and \texttt{R} as either
  \href{namedmat/Contents}{\texttt{namedmat}} objects (i.e.~matrices
  with named rows and columns) or plain numeric arrays.
\item
  \texttt{\textquotesingle{}select=\textquotesingle{}} {[}
  \emph{\texttt{@all}} \textbar{} char \textbar{} cellstr {]} - Return
  ACF for selected variables only; \texttt{@all} means all variables.
\end{itemize}

\paragraph{Description}

\texttt{C} and \texttt{R} are both N-by-N-by-(P+1)-by-NAlt matrices,
where N is the number of measurement and transition variables (including
auxiliary lags and leads in the state space vector), P is the order up
to which the ACF is computed (controlled by the option
\texttt{\textquotesingle{}order=\textquotesingle{}}), and NAlt is the
number of alternative parameterisations in the input model object,
\texttt{M}.

If \texttt{\textquotesingle{}contributions=\textquotesingle{}\ true},
the size of the two matrices is N-by-N-by-(P+1)-by-E-by-NAlt, where E is
the number of all shocks (measurement and transition combined) in the
model.

\subparagraph{ACF with linear filters}

You can use the option
\texttt{\textquotesingle{}filter=\textquotesingle{}} to get the ACF for
variables as though they were filtered through a linear filter. You can
specify the filter in both the time domain (such as first-difference
filter, or Hodrick-Prescott) and the frequncy domain (such as a band of
certain frequncies or periodicities). The filter is a text string in
which you can use the following references:

\begin{itemize}
\tightlist
\item
  \texttt{\textquotesingle{}L\textquotesingle{}}, the lag operator,
  which will be replaced with \texttt{exp(-1i*freq)};
\item
  \texttt{\textquotesingle{}per\textquotesingle{}}, the periodicity;
\item
  \texttt{\textquotesingle{}freq\textquotesingle{}}, the frequency.
\end{itemize}

\paragraph{Example}

A first-difference filter (i.e.~computes the ACF for the first
differences of the respective variables):

\begin{verbatim}
[C,R] = acf(m,'filter=','1-L')
\end{verbatim}

\paragraph{Example}

The cyclical component of the Hodrick-Prescott filter with the smoothing
parameter, \(lambda\), 1,600. The formula for the filter follows from
the classical Wiener-Kolmogorov signal extraction theory,

\[w(L) = \frac{\lambda}{\lambda + \frac{1}{ | (1-L)(1-L) | ^2}}\]

\begin{verbatim}
[C,R] = acf(m,'filter','1600/(1600 + 1/abs((1-L)^2)^2)')
\end{verbatim}

\paragraph{Example}

A band-pass filter with user-specified lower and upper bands. The
band-pass filters can be defined either in frequencies or periodicities;
the latter is usually more convenient. The following is a filter which
retains periodicities between 4 and 40 periods (this would be between 1
and 10 years in a quarterly model),

\begin{verbatim}
[C,R] = acf(m,'filter','per >= 4 & per <= 40')
\end{verbatim}


